RuleManagerService - Installation & Configuration
COMPASS Version 6.2, 6.3, 6.4 © General Re Corporation 2021 - 2026. All Rights Reserved (created: 2026-06-16 generated: 2026-07-10)
| Please note that this document is still under revision, so slight changes still might occur before the final version of this draft. |
Version 6.2
Introduction
COMPASS 6.2 allows a client application to communicate with the COMPASS engine via REST Services. The COMPASS engine consists of the REST components CompassService and RuleManagerService.
From on COMPASS 6.2, the REST services have been split up into CompassService and RuleManagerService: CompassService is Compass' public API (described in detail here), RuleManagerService is the internal API used by RuleManagerApp and not meant for public usage.
Both CompassService and RuleManagerService are Web applications that need to be deployed in a Servlet Container or can run as a Spring Boot application. They work in a stateless manner, and as such it allows easy deployment and scalability including cloud architectures.
This document describes the installation and configuration of the RuleManagerService which is the backend for the RuleManagerApp and provides the necessary REST-services. Please note that this API should not be used by anyone but RuleManagerApp only. The publicly available REST methods provided by COMPASS are documented at REST-API
Prerequisites
RuleManagerService can be deployed in any Java servlet container that supports at least Servlet API 3.0. We recommend the lightweight Java web server Apache Tomcat.
From on version 6.2, RuleManagerService requires Java 11.
Functionality of the RuleManager Service
REST-Services provided by RuleManagerService and used by RuleManagerApp are for internal use only and therefore are not described here.
Installation
The RuleManagerService distribution consists of the archive RuleManagerService.war. It can be deployed
in a Servlet Container (see Deployment in a Servlet Container) or as a standalone application using Spring Boot (see Standalone Server (Spring Boot)).
Deployment in a Servlet Container
RuleManagerService.war containing the RuleManagerService should be deployed in your Servlet
Container (i.e. Tomcat: webapps directory, OpenLiberty: dropins directory). If required, restart the container.
Standalone Server (Spring Boot)
The RuleManagerService.war contains a runnable environment that can be started with the spring WarLauncher. For
quick testing, it is possible to start the WebApp without a third-party Servlet Container:
Copy RuleManagerService.war file to your Compass lib directory.
Make sure Java 11 is installed, and run the following command using Java 11:
java -cp lib\RuleManagerService.war;databaseDriver org.springframework.boot.loader.WarLauncher --spring.configname=RuleManagerService
The delivery includes a batch file bin\startRuleManagerService.bat that starts RuleManagerService as a Spring Boot application.
Configuration
RuleManagerService needs configuration files which define the environment and the data to work with. This configuration-file may use one of the following formats:
| Format | File-Name |
|---|---|
Properties |
RuleManagerService.properties |
YAML |
RuleManagerService.yml |
JSON |
RuleManagerService.json |
Following, we will explain the configuration as properties. The difference between the formats mentioned above are explained in RuleManagerService.properties - application.properties
The main property file is called either RuleManagerService.properties (default file name) or RuleManagerService.yml; in Open Liberty, the file needs to be named application.properties. The contents of the files are described in detail in RuleManagerService.properties - application.properties. We strongly recommend using COMPASS’ ability to use DataSources instead of pure JDBC calls. Therefore, please create the appropriate DataSources (see Data Source properties).
Spring Boot
When the RuleManagerService is started as a Spring Boot application with the batch file bin\startRuleManagerService.bat, the path to the configuration-file is:
config\RuleManagerService.properties
The file name is defined by the --spring.config.name parameter in said file (see Standalone Server (Spring Boot)) and should be located in the [COMPASS-installation]/Config directory.
Apache Tomcat / Standard Servlet Container
The following instructions describe the standard procedure of a deployment within a Standard Servlet Container. As an example, deployment within Apache Tomcat is explained:
When the RuleManagerService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file RuleManagerService.properties to any location and adapt the environment-entry in RuleManagerService/META-INF/context.xml accordingly, i.e.
$CATALINA_HOME/COMPASSConfig/RuleManagerService.properties
The location of the above mentioned file is defined in RuleManagerService/META-INF/context.xml, and can be adapted:
<?xml version="1.0" encoding="UTF-8"?>
<Context path="/">
<Environment name="spring.config.location"
value="file:../COMPASSConfig/RuleManagerService.properties"
type="java.lang.String"/>
The file RuleManagerervice.properties is part of the installation package and will be delivered outside the WAR archive.
Open Liberty / WebSphere
The following instructions describe the procedure of a deployment within an IBM’s Open Liberty. It is also a template for deployment within IBM’s WebSphere. As an example, deployment within Open Liberty is explained:
When RuleManagerService is being deployed in Open Liberty, the file application.properties needs to be placed in $/{server.config.dir} i.e. /opt/wlp/usr/servers/defaultServer.
The default context name of RuleManagerService is "RuleManagerService". If this needs to be changed, the WAR archive of RuleManagerService needs to be unpacked and the file WEB-INF/classes/ibm-web-ext.xml needs to be adapted. The context name can be changed by editing the entry context-root:
<web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
version="1.0">
<reload-interval value="0"/>
<context-root uri="/RuleManagerService"/>
<enable-file-serving value="true"/>
<enable-reloading value="true"/>
</web-ext>
After editing, the WAR archive needs to be re-packed and can be deployed.
Wildfly / JBoss
If you haven’t done so, deploy your database driver to JBoss / Wildfly and create the DataSources needed for COMPASS (see example below). You can also configure RuleManagerService in such a way that it uses pure JDBC connections (see Installation: Database), however, we strongly recommend to use DataSources when deploying RuleManagerService on JBoss / WildFly.
Since there are multiple options specifying DataSources in JBoss / WildFly, our example below shows one possible way to define the DataSources. We therefore adapt %JBOSS_HOME%/standalone/configuration/standalone.xml. If you want to configure the DataSources in a different way, please consult the documentation of your application server or talk to your database administrator.
<subsystem xmlns="urn:jboss:domain:datasources:6.0">
<datasources>
<datasource jndi-name="java:jboss/COMPASSKnowledge" pool-name="COMPASSKnowledge">
<connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<driver>mariadb-java-client-2.7.1.jar</driver>
<security>
<user-name>user</user-name>
<password>password</password>
</security>
<validation>
<valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
<validate-on-match>true</validate-on-match>
<background-validation>false</background-validation>
<exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
</validation>
</datasource>
<datasource jndi-name="java:jboss/COMPASSCache" pool-name="COMPASSCache">
<connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<driver>mariadb-java-client-2.7.1.jar</driver>
<security>
<user-name>user</user-name>
<password>password</password>
</security>
</datasource>
<datasource jndi-name="java:jboss/COMPASSCase" pool-name="COMPASSCase">
<connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<driver>mariadb-java-client-2.7.1.jar</driver>
<security>
<user-name>user</user-name>
<password>password</password>
</security>
</datasource>
</datasources>
</subsystem>
When RuleManagerService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file RuleManagerService.properties to any location and adapt the environment-entry in the deployment descriptor WEB-INF/web.xml accordingly (reminder: you’ll have to re-package the war archive and re-deploy).
Let’s say the configuration file is in $JBOSS_HOME, the entry would look like
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<env-entry>
<env-entry-name>spring.config.location</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>file:../COMPASSConfig/RuleManagerService.properties</env-entry-value>
</env-entry>
</web-app>
|
In JBoss / WildFly, if running them with default logging configuration, the archive SL4J needs to be excluded from COMPASS' classpath. This has already been configured inside the web app at META-INF/jboss-deployment-structure.xml - so if this needs to be changed again, please adapt said file and re-package the war archive. |
<jboss-deployment-structure>
<deployment>
<!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
<exclusions>
<module name="org.slf4j" />
<module name="org.slf4j.impl" />
</exclusions>
</deployment>
</jboss-deployment-structure>
Profiles
RuleManagerService works with profiles regarding Authorization / Authentication.
Depending on the chosen profile, RuleManagerService will either use Spring Authorization (OAuth2) or Keycloak.
It is also possible to run RuleManagerService without any Authorization / Authentication.
The desired Authorization / Authentication option is to specified in the property spring.profiles.active in
the file RuleManagerService.properties or RuleManagerService.yml (see Configuration).
There are 5 profiles available to customize the type of Authorization / Authentication:
| Profile | Explanation |
|---|---|
|
Mandatory |
|
Activate the Keycloak Authorization Configuration |
|
Activate Spring Authorization Configuration |
|
Service Endpoints are not secured. RuleManagerApp does not ask for a user/password |
|
Service Endpoints are not secured. RuleManagerApp will ask for user/password, which will be confirmed by RuleManagerService |
2 profiles need to be specified - default plus the corresponding Authorization profile. The profile default always
needs to be specified plus either one of the profiles keycloakAuthorization, springAuthorization or noAuthorization .
| If not exactly 2 profiles are specified or if the profile default is missing, the application will not start. |
| Profiles | Explanation |
|---|---|
|
RuleManagerService secured by Spring Authorization |
|
RuleManagerService secured by Keycloak Authorization |
|
Endpoints are not secured |
|
Endpoints are not secured |
RuleManagerService.properties - application.properties
Usually, configuration properties are specified in the file RuleManagerService.properties. In Open Liberty (WebSphere), the file application.properties is used instead.
The content of both these files is identical and can be grouped into 4 sections: System properties, Spring Boot related properties, authorization properties and logging properties.
It is also possible to pass the configuration-properties as command-line-parameters to RuleManagerService.
System properties
RuleManagerService stores some information in the property-files mentioned below. Those properties are defined in the file [compass.server.home]/config/server/compass.properties.
In addition, RuleManagerService needs to know the system-name to work with and additional properties when being started.
After modification of any of above-mentioned parameters, the web server should be restarted for the changes to take effect.
The following 3 properties are used to configure these:
| Property Name | Description |
|---|---|
rulemanager.server.home |
Location where the 3 above mentioned files/directory are located. |
rulemanager.systemname |
Name of the system to be used, and which is defined in compass.properties |
rulemanager.fullloadsystem |
true or false: |
Spring Boot properties
The following properties are used to configure RuleManagerService when started outside a Servlet Container but being run as a Spring Boot application.
When running in a Servlet Container, these values are typically defined within the Servlet Container and can be omitted (commented out).
| Property Name | Description |
|---|---|
server.port |
REST service is listening on this port, only relevant if the service is running stand-alone |
server.servlet.contextPath |
REST API prefix, only relevant if service is running stand-alone |
server.sessionTimeout |
timeout, only relevant if the service is running stand-alone |
spring.jmx.enabled |
Don’t expose management beans to the JMX domain |
Data Source properties
The next property allows the definition of a Java Datasource for the database connection to access the: Knowledge Ddta. Set value to "none", if you don’t want to use a DataSource but want to use the database configuration in ${compass.server.home}/config/server/compass.properties Set values to a JNDI Value, if you want to use Datasource of the servlet container. For Apache Tomcat, define <ResourceLink> in context.xml and <Resource> in server.xml needs to be defined..
| Property Name | Description |
|---|---|
knowledge.datasource.jndi |
Datasource for knowledge data |
Should the entry xxxxxx.datasource.jndi be set to none or to a value that has not really been defined in the servlet container, a JDBC database connection will be created using the system-properties from the file $\{compass.server.home}/config/server/compass.properties.
When defining the Datasource for the Knowledge Data, the corresponding connection-properties in the compass.properties-file can be omitted:
Knowledge Data:
[System-name].database.url
[System-name].database.driver
[System-name].database.user
[System-name].database.password
Authorization properties
This part is only required when the RuleManagerService is used together with the COMPASS Authorization Server (OAuth2), meaning the profiles default and `springAuthorization`are activated (see Profiles). The installation of COMPASS Authorization Server providing OAuth2-authorization is described in the document Authorization Server. The corresponding properties are described in the document REST-API-Security
| Property Name | Description |
|---|---|
compass.security.enabled |
define if security is enabled |
compass.security.cors,enabled |
define if CORS is enabled |
compass.security.cors.crossOrigin.urls |
specify URLs for which CORS is allowed. URLs have to be entered incl. protocol (i.e. http / https) and port. Multiple URLs cam be entered as a list separated by comma |
compass.security.resource_id |
define the security resource id |
compass.security.oauthServerUrl |
define the OAuth server URL for the check_token method |
compass.security.clientId |
define the client id for the oauth server |
compass.security.clientSecret |
define the client password for the oauth server |
compass.security.tokenValidationTimeout |
define the timeout for the validation token (0 = no timout) |
spring.security.oauth2.resourceserver.jwt.issuer-uri |
In case you want to integrate with Keycloak, specify the URL for the specific Keycloak-realm |
RuleManagerService - configuration examples
Example configuration via property-file
Details
# COMPASS 6.2 RuleManagerService Properties
#
# this block is only relevant if the service is running stand-alone
# RuleManager service is listening on this port
server.port=8086
# REST API prefix
server.servlet.contextPath=/RuleManagerService
# timeout, in seconds
server.sessionTimeout=60
#
# REST api Version
rulemanager.parameter.apiVersion=1.0
#
# Don't expose management beans to the JMX domain.
spring.jmx.enabled=false
# Logging
# log levels
logging.level.root=INFO
logging.level.org.springframework.web=INFO
# set COMPASS REST logging to debug
logging.level.com.cr.compass.rest=DEBUG
logging.level.com.cr.compass.rest.term=INFO
# set the FOP engine outputs only to error
logging.level.org.apache.fop=ERROR
#
# logging of Requests
logging.level.org.springframework.web.filter.CommonsRequestLoggingFilter=INFO
#
# logging file - comment out the relevant
# for running stand-alone or for running in tomcat
logging.file.name=./log/RuleManagerService.log
# Logging pattern for the logging file and console
logging.pattern.file=%d{ISO8601} [%-5level] %logger{15}:%L - %msg%n
logging.pattern.console=%d{ISO8601} [%highlight(%-5level)] %cyan(%logger{15}:%L) - %msg%n
#
# Logging-Area of the COMPASS kernel
rulemanager.loggingarea=0
#
# COMPASS properties files location - comment out the relevant
# COMPASS properties files are in an absolute path or relative path (starting with . )
rulemanager.server.home=./configSamples
# COMPASS properties files are under user.home to catalina home
#rulemanager.server.home=${CATALINA_HOME}/COMPASSConfig
# you need these files and directories for a service installation
# ${rulemanager.server.home}/config/server/compass.properties
# ${rulemanager.server.home}/config/server/EMConversion.properties
# ${rulemanager.server.home}/config/script/*.*
#
# System to use, must be declared in ${rulemanager.server.home}/config/server/compass.properties
rulemanager.systemname=aSystem
# the COMPASS system is being preloaded in all cases. The next property describes if the preload includes the whole (full) database
rulemanager.fullloadsystem=false
# DataSources Configuration
# set value to "none", if you don't want to use DataSources
# and you want to use the database configuration in ${rulemanager.server.home}/config/server/compass.properties
knowledge.datasource.jndi=none
# set values to a JNDI Value, if you want to use DataSources of the servlet container
# for tomcat define <ResourceLink> in context.xml and <Resource> in server.xml for knowledge DataSources
#knowledge.datasource.jndi=java:/comp/env/jdbc/COMPASSKnowledge
# login check should be enabled only for RuleManagerService
compass.login.check.enabled=true
# COMPASS PROFILE. Check Readme file for more details on profile #
spring.profiles.active=default,noAuthorization
# authentication and authorization
# CORS POLICY
compass.security.cors.enabled=true
compass.security.cors.crossOrigin.urls=http://aHost:8085,http://anotherHost:4200
# SPRING AUTHORIZATION #
# define the oauth server url for the check_token method
compass.security.oauthServerUrl=http://aHost:8080/CompassAuthorization/oauth/check_token
# define the security resource id
compass.security.resource_id=compass-service
# define the client id for the oauth server
compass.security.clientId=rm-client
# define the client pwd for the oauth server
compass.security.clientSecret=rm-client-secret
# define the token validation timeout in minutes if security is enabled.
# Authorization Token will be validated only after the specified timeout in minutes
compass.security.tokenValidationTimeout=0
# SPRING AUTHORIZATION END #
# KEYCLOAK AUTHORIZATION #
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://aHost:8085/realms/RuleManager
# KEYCLOAK AUTHORIZATION END #----
Example configuration via YAML-file
Details
# config RuleManagerService for 6.2
server:
port: '8086'
servlet:
contextPath: "/RuleManagerService"
rulemanager:
systemname: aSystem
parameter:
fullloadsystem: false
loggingarea: 0
compass:
language: en
login:
check:
enabled: true
database:
global:
url: jdbc:mariadb://aHost:3306/aDatabase
driver: org.mariadb.jdbc.Driver
user: aUser
password: aPassword
security:
cors:
enabled: true
crossOrigin:
urls: http://aHost:8085,http://anotherHost:4200
clientId: rm-client
clientSecret: rm-client-secret
oauthServerUrl: http://aHost:8080/CompassAuthorization/oauth/check_token
resource_id: compass-service
tokenValidationTimeout: 0
logging:
file:
name: ./log/RuleManagerService.log
level:
root: INFO
com:
cr:
compass:
rest: DEBUG
pattern:
file: "%d{ISO8601} [%-5level] %logger{15}:%L - %msg%n"
console: "%d{ISO8601} [%highlight(%-5level)] %cyan(%logger{15}:%L) - %msg%n"
spring:
profiles:
active: default,noAuthorization
security:
oauth2:
resourceserver:
jwt:
issuer-uri: http://10.130.130.115:8085/realms/RuleManager----
Example configuration via JSON-file / JSON parameter
Details
{
"server": {
"port": "8086",
"servlet": {
"contextPath": "/RuleManagerService"
}
},
"rulemanager": {
"systemname": "aSystem",
"parameter": {
"fullloadsystem": false,
"loggingarea": 0
}
},
"compass": {
"language": "en",
"login":{
"check": {
"enabled": true
}
},
"database": {
"global": {
"url": "jdbc:mariadb://aHost:3306/aDatabase",
"driver": "org.mariadb.jdbc.Driver",
"user": "aUser",
"password": "aPassword"
}
},
"security": {
"cors": {
"enabled": true,
"crossOrigin": {
"urls": "http://aHost:8085,http://anotherHost:4200"
}
},
"clientId": "rm-client",
"clientSecret": "rm-client-secret",
"oauthServerUrl": "http://aHost:8080/CompassAuthorization/oauth/check_token",
"resource_id": "compass-service",
"tokenValidationTimeout": 0
}
},
"logging": {
"file": {
"name": "./log/RuleManagerService.log"
},
"level": {
"root": "INFO",
"com": {
"cr": {
"compass": {
"rest": "DEBUG"
}
}
}
},
"pattern": {
"file": "%d{ISO8601} [%-5level] %logger{15}:%L - %msg%n",
"console": "%d{ISO8601} [%highlight(%-5level)] %cyan(%logger{15}:%L) - %msg%n"
}
},
"spring": {
"profiles": {
"active": "default,noAuthorization"
},
"security": {
"oauth2": {
"resourceserver": {
"jwt": {
"issuer-uri": "http://10.130.130.115:8085/realms/RuleManager"
}
}
}
}
}
}
Integration with Keycloak
In order to run RuleManagerService, the following profiles have to be activated in the file RuleManagerService.properties or RuleManagerService.yaml (see RuleManagerService.poperties / application.properties. A Customer Keycloak Realm Issuer URL needs to be configured.
| The Issuer Url can be found if you open Keycloak Admin Console, select the corresponding Realm and click Realm Settings. On the right side, you will find the OpenID Endpoint Configuration link. Click the link, it will open a new tab and on the beginning, you will find the Issuer Url. |
"issuer":"http://localhost:8080/realms/RuleManagerApp"
spring.profiles.active=default,keycloakAuthorization
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/RuleManagerApp
Logging
RuleManager Service
In RuleManagerService logging can be configured as properties in the file RuleManagerService.[properties | yaml | json]. For a full overview about properties and logging features in RuleManagerService, see Properties Overview of RuleManagerService.
For real-world examples of how to configure RuleManagerService, see How to pass properties.
Verifying the installation
After updating the configuration-file, the installation needs to be verified.
For both installation types (Spring Boot app - standalone - or deployment in a Servlet Container, please perform the following steps:
Deployment as Spring Boot app (stand-alone)
-
Start RuleManagerService as Spring Boot app (stand-alone):
[COMPASS-installation-directory]/bin/startRESTService.bat
-
Verify in your console, that RuleManagerService started:
In the CMD-window or the log-file specified, you should see a message like
2023-03-14 13:05:47,299 [INFO ] c.c.c.r.RuleManagerServiceApp:61 - Started RuleManagerServiceApp in 65.43 seconds (JVM running for 308.249)
Deployment in Servlet Container
Perform the following steps:
-
Start the Servlet Container if not already started and deploy the application
-
Check that the RuleManagerService was deployed correctly (using administration tools of your Web Server).
-
Alternatively, you can check the logfile you’ve specified: It should contain an entry like
2023-03-14 13:05:47,299 [INFO ] c.c.c.r.RuleManagerServiceApp:61 - Started RuleManagerServiceApp in 65.43 seconds (JVM running for 308.249)